---
type: integration
title: '@astrojs/mdx'
description: 了解如何在你的 Astro 项目中使用 @astrojs/mdx 集成。
githubIntegrationURL: 'https://github.com/withastro/astro/tree/main/packages/integrations/mdx/'
category: other
i18nReady: true
---
import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
import ReadMore from '~/components/ReadMore.astro'

此 **[Astro 集成][astro-integration]** 能够使用 [MDX](https://mdxjs.com/) 组件，并允许你通过 `.mdx` 文件创建页面。

## 为什么是 MDX？

MDX 允许你在 Astro 项目的 [Markdown 内容中使用变量、JSX 表达式和组件](/zh-cn/guides/markdown-content/#mdx-独有特性)。如果你有现有的用 MDX 编写的内容，这个集成允许你把这些文件带到你的 Astro 项目中。

## 安装

Astro 包含了一个 `astro add` 命令，用于自动设置官方集成。如果你愿意，可以改为[手动安装集成](#手动安装)。

在新的终端窗口中运行下面其中一个命令。

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npx astro add mdx
    ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm astro add mdx
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn astro add mdx
  ```
  </Fragment>
 </PackageManagerTabs>

如果你遇到任何问题，[请随时在 GitHub 上向我们报告](https://github.com/withastro/astro/issues)并尝试下面的手动安装步骤。

### 手动安装

首先，安装 `@astrojs/mdx` 包： 

<PackageManagerTabs>
  <Fragment slot="npm">
  ```sh
  npm install @astrojs/mdx
  ```
  </Fragment>
  <Fragment slot="pnpm">
  ```sh
  pnpm add @astrojs/mdx
  ```
  </Fragment>
  <Fragment slot="yarn">
  ```sh
  yarn add @astrojs/mdx
  ```
  </Fragment>
</PackageManagerTabs>

然后，使用 `integrations` 属性将集成应用到你的 `astro.config.*` 文件中：

```js title="astro.config.mjs" ins={2} ins="mdx()"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
export default defineConfig({
  // ...
  integrations: [mdx()],
});
```

### 编辑器集成

对于 [VS Code](https://code.visualstudio.com/) 的编辑器支持，请安装[官方的 MDX 扩展](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx)。

对于其他编辑器，请使用 [MDX 语言服务器](https://github.com/mdx-js/mdx-analyzer/tree/main/packages/language-server)。

## 使用

通过 Astro MDX 集成，你可以在你的 `src/pages/` 目录下添加 `.mdx` 文件来[添加 MDX 页面到你的项目](/zh-cn/guides/markdown-content/#markdown-和-mdx-页面)。你也可以[导入 `.mdx` 文件](/zh-cn/guides/markdown-content/#导入-markdown)到 `.astro` 文件。

Astro 的 MDX 集成为标准的 MDX 增加了额外的功能，包括 Markdown 风格的 frontmatter。这允许你使用大部分 Astro 的内置 Markdown 功能，比如一个[特殊的 frontmatter`layout` 属性](/zh-cn/guides/markdown-content/#frontmatter-layout)。

在我们的 [Markdown & MDX 指南](/zh-cn/guides/markdown-content/)中可以看到 MDX 在 Astro 中的工作原理和例子。

访问 [MDX 文档](https://mdxjs.com/docs/what-is-mdx/)，了解使用标准 MDX 功能的情况。

## 配置

一旦 MDX 集成被安装，在你的 Astro 项目中使用 `.mdx` 文件就不需要配置。

你可以通过以下选项配置你的 MDX 的渲染方式：

* [继承自 Markdown 配置的选项](#继承自-markdown-配置的选项)
* [`extendMarkdownConfig`](#extendmarkdownconfig)
* [`recmaPlugins`](#recmaplugins)
* [`优化`](#优化)

### 继承自 Markdown 配置的选项

所有 [`markdown` 配置选项](/zh-cn/reference/configuration-reference/#markdown-选项)都可以在 MDX 集成中单独配置。这包括 remark 和 rehype 插件、语法高亮等。选项将默认为你的 Markdown 配置中的选项（[请参阅 `extendMarkdownConfig` 选项](#extendmarkdownconfig)来修改此选项）。

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';
import remarkToc from 'remark-toc';
import rehypeMinifyHtml from 'rehype-minify-html';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      syntaxHighlight: 'shiki',
      shikiConfig: { theme: 'dracula' },
      remarkPlugins: [remarkToc],
      rehypePlugins: [rehypeMinifyHtml],
      remarkRehype: { footnoteLabel: 'Footnotes' },
      gfm: false,
    }),
  ],
});
```

:::caution
MDX 不支持以字符串形式传递备注和 rehype 插件。你应该安装、导入并应用插件功能来代替。
:::

<ReadMore>参见 [Markdown 选项参考](/zh-cn/reference/configuration-reference/#markdown-选项) 以获得完整的选项列表。</ReadMore>

### `extendMarkdownConfig`

* **类型：** `boolean`
* **默认值：** `true`

MDX 将默认扩展[你的项目现有的 Markdown 配置](/zh-cn/reference/configuration-reference/#markdown-选项)。要覆盖个别选项，你可以在你的 MDX 配置中进行等价配置。

例如，假设你需要禁用 GitHub-Flavored Markdown，并为 MDX 文件应用一套不同的注释插件。你可以像这样应用这些选项，`extendMarkdownConfig` 默认为启用：

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // 继承自 Markdown 的 `syntaxHighlight`

      // Markdown `remarkPlugins` 被忽略，
      // 只启用 `remarkPlugin2`。
      remarkPlugins: [remarkPlugin2],
      // `gfm` 被重写为 `false`
      gfm: false,
    }),
  ],
});
```

你可能还需要在 MDX 中禁用 `markdown` 配置扩展。为此，将 `extendMarkdownConfig` 设置为 `false`：

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  markdown: {
    remarkPlugins: [remarkPlugin1],
  },
  integrations: [
    mdx({
      // Markdown 配置现在被忽略了
      extendMarkdownConfig: false,
      // `remarkPlugins` 没有启用
    }),
  ],
});
```

### `recmaPlugins`

这些是直接修改输出 [estree](https://github.com/estree/estree) 的插件。这对于在你的 MDX 文件中修改或注入 JavaScript 变量很有用。

我们建议[使用 AST Explorer](https://astexplorer.net/)来处理 estree 的输出，并尝试 [`estree-util-visit`](https://unifiedjs.com/explore/package/estree-util-visit/) 来搜索整个 JavaScript 节点。

### 优化

* **类型：** `boolean | { customComponentNames?: string[] }`

这是一个可选的配置设置，用于优化 MDX 输出，以便通过内部 rehype 插件加快构建和渲染速度。如果你的 MDX 文件较多，并注意到构建速度较慢，这可能会很有用。不过，该选项可能会生成一些未转义的 HTML，因此请确保你网站的交互式部分在启用该选项后仍能正常工作。

默认情况下是禁用的。要启用 MDX 优化，请在 MDX 集成配置中添加以下内容：

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: true,
    }),
  ],
});
```

#### customComponentNames

* **类型：** `string[]`

`optimize` 的一个可选属性，用于防止 MDX 优化器处理[通过组件属性传递给导入的 MDX 内容的任何自定义组件](/zh-cn/guides/markdown-content/#使用导入的-mdx-的自定义组件)。

你需要将这些组件从优化中排除，因为优化器会急切地将内容转换为静态字符串，这将破坏需要动态呈现的自定义组件。

例如，以下内容的预期 MDX 输出应为 `<Heading>...</Heading>`，而不是每个 `"<h1>...</h1>"`：

```astro
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---

<Content components={{ ...components, h1: Heading }} />
```

要使用 `customComponentNames` 属性配置此优化，指定应视为自定义组件的 HTML 元素名称数组：

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  // ...
  integrations: [
    mdx({
      optimize: {
        // 防止优化器处理 `h1` 元素
        // 这些元素将被视为自定义组件
        customComponentNames: ['h1'],
      },
    }),
  ],
});
```

请注意，如果你的 MDX 文件[使用 `export const components = {...}` 配置自定义组件](/zh-cn/guides/markdown-content/#将自定义组件分配给-html-元素)，则你无需手动配置此选项。优化器将自动检测它们。


## 例子

* [Astro MDX 启动模板](https://github.com/withastro/astro/tree/latest/examples/with-mdx)显示了如何在你的 Astro 项目中使用 MDX 文件。

[astro-integration]: /zh-cn/guides/integrations-guide/

[astro-ui-frameworks]: /zh-cn/guides/framework-components/#使用框架组件
